---
title: "Badge"
description: "Badges are used as a small numerical value or status descriptor for UI elements."
---

import {badgeContent} from "@/content/components/badge";

# Badge

Badges are used as a small numerical value or status descriptor for UI elements.

<ComponentLinks component="badge" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add badge",
    npm: "npm install @heroui/badge",
    yarn: "yarn add @heroui/badge",
    pnpm: "pnpm add @heroui/badge",
    bun: "bun add @heroui/badge"
  }}
/>


## Import

<ImportTabs
  commands={{
    main: 'import {Badge} from "@heroui/react";',
    individual: 'import {Badge} from "@heroui/badge";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={badgeContent.usage} />

### Sizes

<CodeDemo title="Sizes" files={badgeContent.sizes} />

### Colors

<CodeDemo title="Colors" files={badgeContent.colors} />

### Variants

<CodeDemo title="Variants" files={badgeContent.variants} />

### Placements

<CodeDemo title="Placements" files={badgeContent.placements} />

### Shapes

For a better positioning, you can use the `shape` property to define the shape of the badge.

<CodeDemo title="Shapes" files={badgeContent.shapes} />

### Badge Visibility

You can control the visibility of the badge by using the `isInvisible` property.

<CodeDemo title="Badge visibility" files={badgeContent.visibility} />

### Content Examples

<CodeDemo title="Content examples" files={badgeContent.contentExamples} />

### Disable Outline

By default, the badge has an outline, you can disable it by using the `showOutline={false}` property.

<CodeDemo title="Disable outline" files={badgeContent.showOutline} />

### Accessibility

It's not advisable to depend on the badge's content for accurate announcement.
Instead, consider supplying a comprehensive description, such as using `aria-label`.

<CodeDemo title="Accessibility" files={badgeContent.a11y} />

<Spacer y={4} />

## Slots

The Badge component has two slots:

- **base**: The base slot for the badge, which is the container of the badge.

- **badge**: The main slot for the badge content, which is the content of the badge.

<Spacer y={4} />

## API

### Badge Props

<APITable
  data={[
    {
      attribute: "children",
      type: "ReactNode",
      description: "The wrapped component.",
      default: "-"
    },
    {
      attribute: "content", 
      type: "string | number | ReactNode",
      description: "The content of the badge. The badge will be rendered relative to its children.",
      default: "-"
    },
    {
      attribute: "variant",
      type: "solid | flat | faded | shadow",
      description: "The variant style of the badge.",
      default: "solid"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The color of the badge.",
      default: "default"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The size of the badge.",
      default: "md"
    },
    {
      attribute: "shape",
      type: "circle | rectangle",
      description: "The shape of the badge.",
      default: "rectangle"
    },
    {
      attribute: "placement",
      type: "top-right | top-left | bottom-right | bottom-left",
      description: "The placement of the badge.",
      default: "top-right"
    },
    {
      attribute: "showOutline",
      type: "boolean",
      description: "If `true`, the badge will have an outline.",
      default: "true"
    },
    {
      attribute: "disableOutline",
      type: "boolean", 
      description: "If `true`, the badge will not have an outline. **Deprecated** use `showOutline` instead.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "If `true`, the badge will not have an animation.",
      default: "false"
    },
    {
      attribute: "isInvisible",
      type: "boolean",
      description: "If `true`, the badge will be invisible.",
      default: "false"
    },
    {
      attribute: "isOneChar",
      type: "boolean",
      description: "If `true`, the badge will have the same width and height.",
      default: "false"
    },
    {
      attribute: "isDot",
      type: "boolean",
      description: "If `true`, the badge will have smaller dimensions.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\"｜\"badge\", string>>",
      description: "Allows to set custom class names for the badge slots.",
      default: "-"
    }
  ]}
/>
